<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<title>jQuery Plasma Plug-in</title>
		<script src="jquery-1.5.2.min.js" type="text/javascript"></script>
    <script src="jquery.plasma-0.5.js" type="text/javascript"></script>
    <script src="plasma.chars.js" type="text/javascript"></script>
    <script src="plasma.script.js" type="text/javascript"></script>
		<script type="text/javascript">
		</script>
		<style type="text/css">
		  #plasma {}
			#plasma table {background-color:black;}
			#plasma td {font-size:0; line-height:0;}
			
			code {display:block; margin:1em 0; padding:0 1em; white-space:pre-wrap; background-color:#ddd; border:solid 1px #aaa;}
      dt {font-weight:bold;}
      dt span {font-weight:normal;}
		</style>
	</head>
	<body>
		<h1>jQuery Plasma Plug-in</h1>
<p>The jQuery Plasma Plug-in creates a dynamic plasma display by applying an HSV to RGB conversion on a 
	Sine wave transformation. It supports many option, all of which can be set before initalization or 
	during run-time.</p>
<p>This project is hosted on <a href="http://code.google.com/p/jquery-plasma/">Google Code</a> and can also be found in the <a href="http://plugins.jquery.com/project/jquery-plasma">jQuery Plug-in repository</a>. The Google Code site will always have the latest software.</p><h2>Demonstration</h2>
<div id="plasma"></div><br />
<form action="#" method="get" id="plasma-controls">
  <fieldset>
    <legend>Global Controls</legend>
    <button id="stop">Stop</button>
    <button id="start">Start</button>
    <label>Delay</label>
    <input id="delay" type="text" size="4" />
    <button id="destroy">Destroy</button>
  </fieldset>
  <fieldset>
    <legend>Plasma Controls</legend>
    <label>Plasma Type</label>
    <select id="plasma_type">
      <option value="hsv">HSV</option>
      <option value="rgb">RGB</option>
    </select>
    <label>Blur</label>
    <input id="blur" type="text" size="4" /><br />
    <label>R</label>
    <input id="r" type="text" size="4" />
    <label>G</label>
    <input id="g" type="text" size="4" />
    <label>B</label>
    <input id="b" type="text" size="4" />
    <label>H</label>
    <input id="h" type="text" size="4" />
    <label>S</label>
    <input id="s" type="text" size="4" />
    <label>V</label>
    <input id="v" type="text" size="4" /><br />
  </fieldset>
  <fieldset>
    <legend>Overlay Controls</legend>
    <label>Overlay Color</label>
    <input id="overlay_color" type="text" size="12" />
    <label>Overlay Bias</label>
    <input id="overlay_bias" type="text" size="4" />
    <label>Loop</label>
    <input id="overlay_loop" type="checkbox" /><br />
    <button id="overlay">Toggle Static Overlay</button>
    <button id="overlay_anim">Toggle Animated Overlay</button>
    <label>Animation Delay</label>
    <input id="overlay_delay" type="text" size="4" /><br />
    <button id="overlay_text">Toggle Scrolling Overlay</button>
    <label>Text</label>
    <input id="overlay_data" type="text" value="The jQuery Plasma Plug-in" size="24" />
    <label>Scroll Delay</label>
    <input id="scroll_delay" type="text" size="4" />
  </fieldset>
</form>
<p id="controls">
</p>
<h3>Simple implementation</h3>
<p>The plug-in can be run without specifying any parameters with the following HTML</p>
<code>
&lt;div id="plasma"&gt;&lt;/div&gt;

</code>
<p>and this JavaScript statement.</p>
<code>
$(document).ready(function(){
  $('#plasma').plasma();
});

</code>
<h3>Advanced implementation</h3>
<p>The plug-in also supports many user-defined settings that can dramatically alter the appearance of the plasma.</p>
<code>
var options = {
  // table settings, only read during initialization
  rows: 8, // more rows = more processing cycles
  cols: 8, // more cols = more processing cycles
  spacing: 0, // table's cellspacing attribute
  padding: 0, // table's cellpadding attribute
  border: 0, // table's border attribute
  height: '40px', // css height property for each cell
  width: '40px', // css height property for each cell
  html: '', // each cell can contain some html
  // timer settings
  shift: 0, // any positive integer
  delay: 100, // milliseconds between frame refresh
  overlay_delay: 1000, // overlay animation speed milliseconds
  scroll_delay: 100, // scroll speed milliseconds
  // plasma settings
  plasma_type: 'hsv', // so far, 'hsv' or 'rgb', more to come
  blur: 1, // less than 1 sharpens the plasma, greater than 1 blurs
  r: 1, // red intensity 0-1, applies to plasma_type 'rgb'
  g: 1, // green intensity 0-1, applies to plasma_type 'rgb'
  b: 1, // blue intensity 0-1, applies to plasma_type 'rgb'
  h: 255, // hue multiplier, applies to plasma_type 'hsv'
  s: 1, // saturation intensity 0-1, applies to plasma_type 'hsv'
  v: 1, // value intensity 0-1, applies to plasma_type 'hsv'
  // overlay settings
  overlay: false, // boolean, on or off
  overlay_anim: false, // boolean true = animated, false = static
  overlay_loop: true, // boolean, true = loop, false = play once
  overlay_color: [255, 255, 255], // array of rgb values 0-255
  overlay_bias: [0,0],  // x,y cells to move overlay 
  overlay_data: [] // array for overlay pattern
};

$(document).ready(function(){
  $('#plasma').plasma(options);
});
</code>
<h3>Run-time Manipulation</h3>
<p>The jQuery Plasma Plug-in presents an interface for controlling some aspects of the display. All of the settings for the jQuery 
	Plasma Plug-in can be manipulated after instantiation through jQuery's data object, allowing for on the fly changes. The methods
	available are start, stop, show_overlay(pattern), hide_overlay, and destroy.</p>
<code>
&lt;div id="plasma"&gt;&lt;/div&gt;
&lt;button id="overlay"&gt;Overlay text&lt;/button&gt;
</code>
<p> The example below attaches the plug-in's show_overlay method to a button click handler.</p>
<code>
$(document).ready(function(){
  $('#plasma').plasma();
  $('#overlay').click(function(){
    var pattern = "This is the jQuery Plasma Plug-in";
    $('#plasma').plasma('show_overlay', pattern);
    return false;
  });
});
</code>
<h3>Settings Details</h3>
<dl>
  <h4>Table settings</h4>
	<dt>rows <span>default value: 8</span></dt>
	<dd>A positive integer describing the number of table rows in the plasma display. Remember,
		more rows means more processing cycles. A slower computer and/or browser can be brought 
		to its knees through a combination of the rows, cols, and delay settings.</dd>
	<dt>cols <span>default value: 8</span></dt>
	<dd>A positive integer describing the number of table columns in the plasma display. Remember,
		more columns means more processing cycles. A slower computer and/or browser can be brought 
		to its knees through a combination of the rows, cols, and delay settings.</dd>
	<dt>spacing <span>default value: 0</span></dt>
	<dd>A positive integer describing plasma display table's cellspacing attribute.</dd>
	<dt>padding <span>default value: 0</span></dt>
	<dd>A positive integer describing plasma display table's cellpadding attribute.</dd>
	<dt>border <span>default value: 0</span></dt>
	<dd>A positive integer describing plasma display table's border attribute.</dd>
	<dt>height <span>default value: '40px'</span></dt>
	<dd>A CSS height value applied to each &lt;td&gt; element in the plasma display. Any valid
		CSS height property can be used here, and each table cell in the plasma display will
		render as &lt;td style="height:[settings.height];"&gt;.</dd>
	<dt>width <span>default value: '40px'</span></dt>
	<dd>A CSS width value applied to each &lt;td&gt; element in the plasma display. Any valid
		CSS width property can be used here, and each table cell in the plasma display will
		render as &lt;td style="width:[settings.width];"&gt;.</dd>
	<dt>html <span>default value: ''</span></dt>
	<dd>Each table cell in the plasma display can contain any valid html. For example, setting
		html to &lt;img src="circle-white.png" /&gt; would render each cell as &lt;td&gt;&lt;img src="circle-white.png" /&gt;&lt;td&gt;. 
		Care should be taken to match cell contents width cell height/width.</dd>
  <h4>Timer settings</h4>
  <dt>shift <span>default value: 0</span></dt>
  <dd>The shift setting can also be thought of as a time counter, it advances by on every cell, thoughout the animation cycle. For example, on a 8x8 plasma matrix
    at 10 frames per second (settings.delay = 100) shift will advance approximately 640 (8x8x10). This is an experimental setting, but it seems almost any integer
    is possible, I have seen values as high as 126000.</dd>
  <dt>delay <span>default value: 100</span></dt>
  <dd>The delay setting indicates the time in milliseconds between each plasma display frame update. Lower settings will speed up the disply, but can have an adverse 
    affect on performance.</dd>
  <dt>overlay_delay <span>default value: 1000</span></dt>
  <dd>The overlay_delay setting indicates the time in milliseconds between each frame of an animated overlay. Lower settings will speed up the disply, but can have an adverse 
    affect on performance. Requires overlay_anim: true.</dd>
  <dt>scroll_delay <span>default value: 100</span></dt>
  <dd>The scroll_delay setting indicates the time in milliseconds between each advance of an scrolling overlay. Lower settings will speed up the disply, but can have an adverse 
    affect on performance. Requires overlay_data: {string}.</dd>
  <h4>Plasma settings</h4>
  <dt>plasma_type <span>default value: 0</span></dt>
  <dd>The type setting switches between different algorithms used to create the plasma. Currently only values of 'hsv' or 'rgb' are supported. The 'hsv' plasma can be manipulated
  with the h, s, v settings while the 'rgb' plasma can be manipulated with the r, g, b settings.</dd>
  <dt>blur <span>default value: 0</span></dt>
  <dd>The blur setting, in conjunction with settings.type, adjusts the color separation of the plasma. A value between 0 and 1 with sharpen the display, while a value
    over 1 (2,4,10...) with blur the plasma.</dd>
  <dt>r, g, b <span>default value: 1</span></dt>
  <dd>The r, g, b settings are modifiers to the final background color. The color that should be displayed is multiplied by by each modifier to reach the final display color.
    These settings are highly experimental, and results cannot be accurately predicted.</dd>
  <dt>h, s, v <span>default value: h:255, s:1, v:1</span></dt>
  <dd>The h, s, v settings are modifiers to the HSV to RGB conversion. These settings are highly experimental, and results cannot be accurately predicted.</dd>
  <h4>Overlay settings</h4>
	<dt>overlay <span>default value: false</span></dt>
	<dd>A boolean value indicating whether the overlay described in settings.pattern is displayed.</dd>
	<dt>overlay_color <span>default value: [255, 255, 255] (white)</span></dt>
	<dd>The overlay_color setting can take two forms; as an array, this setting specifies the RGB values for each cell. If a float is
		specified, the underlying plasma will be adjusted by this value. For example, if overcolor is set to 0.3, pattern cells witha value
		of 1 will be 30% of the brightness of the underlying plasma, this creates a semi-transparent effect not possible by setting the RGB values directly.</dd>
	<dt>overlay_data <span>default value: []</span></dt>
	<dd>The pattern setting can take a number of forms. It can be a 2-dimensional array of 1's and 0's indicating which
		cells in the plasma display will be altered. 0 will show the underlying plasma color, 1 will show the settings.overlay_color.
		<code>
var options = {
  pattern: [
    [0,0,0,0,0,0,0,0],
    [0,1,1,1,1,1,1,0],
    [0,1,0,0,0,0,1,0],
    [0,1,0,1,1,0,1,0],
    [0,1,0,1,1,0,1,0],
    [0,1,0,0,0,0,1,0],
    [0,1,1,1,1,1,1,0],
    [0,0,0,0,0,0,0,0]
  ]
};
  </code> 
  A more advanced static pattern array indicates a specific color for each cell by using an array of color value instead of a 1 integer. 
	As before, 0 will show the underlying plasma color.
	<code>
var options = {
  pattern: [
    [0,  0,  0,         0,         0,         0,         0,  0],
    [0,  1,  1,         1,         1,         1,         1,  0],
    [0,  1,  [255,0,0], [255,0,0], [255,0,0], [0,255,0], 1,  0],
    [0,  1,  [0,0,0],   0,         0,         [0,255,0], 1,  0],
    [0,  1,  [0,0,0],   0,         0,         [0,255,0], 1,  0],
    [0,  1,  [0,0,0],   [0,0,255], [0,0,255], [0,0,255], 1,  0],
    [0,  1,  1,         1,         1,         1,         1,  0],
    [0,  0,  0,         0,         0,         0,         0,  0]
  ]
};
  </code> 
  An animated pattern would be an array of single frame patterns, and requires settings.overlay_anim = true
  <code>
var options = {
  pattern: [
    [
      [0,0,0,1,1,0,0,0],
      [0,0,1,1,1,1,0,0],
      [0,1,1,1,1,1,1,0],
      [1,1,0,1,1,0,1,1],
      [1,1,1,1,1,1,1,1],
      [0,0,1,0,0,1,0,0],
      [0,1,0,1,1,0,1,0],
      [1,0,1,0,0,1,0,1]
    ],[
      [0,0,0,1,1,0,0,0],
      [0,0,1,1,1,1,0,0],
      [0,1,1,1,1,1,1,0],
      [1,1,0,1,1,0,1,1],
      [1,1,1,1,1,1,1,1],
      [0,0,1,0,0,1,0,0],
      [0,1,0,0,0,0,1,0],
      [0,0,1,0,0,1,0,0]
    ]
  ]
};
  </code>
  A third option is to pass a string in as settings.overlay_data. This option requires plasma.chars.js (included with distribution) 
    and will scroll the text from right to left across the plasma display.</dd>
</dl>
<h3>Changelog</h3>
<h4>jQuery Plasma 0.5 (beta 3)</h4>
<p>re-engineered delay counters<br />
added overlay bias (position adjust)<br />
added support for animated overlays</p>
<h4>jQuery Plasma 0.4 (beta 2)</h4>
<p>added overlay for image or scrolling text<br />
removed limit to time shift (found to be ineffective)
</p>
<h4>jQuery Plasma 0.3 (beta 1)</h4>
<p>submitted to jQuery plug-in repository<br />
added different plasma algorithms settings.type<br />
added a limit to the time shift parameter
</p>
<h4>jQuery Plasma 0.2</h4>
<p>optimized the delay timer<br />
added start, stop, destroy methods<br />
added data support for settings to allow on the fly changes</p>
<h4>jQuery Plasma 0.1</h4>
<p>Initial release, not really ready for prime time</p>
</body>
</html>
